Skip to main content

WhatsApp Business Webhook

Business needs to provide the endpoint URL where the notification events will be sent.

API Endpoint​

Provided by the business

Authentication Methods Supported​

Both Basic and Bearer Token methods are supported. If Basic method is chosen, business needs to set the username and password. In case of Bearer method, the corresponding token will be configured by the business.

1. Outbound Message Status Updates​

Delivered automatically as messages transition through lifecycle states (sent, delivered, read, failed).

A. Delivered Status​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "order_update_123",
  "subscriberId": "919672242292",
  "status": "delivered",
  "deliveredAt": 1788939562
}

B. Sent Status​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "order_update_123",
  "subscriberId": "919672242292",
  "status": "sent",
  "sentAt": 1788939560
}

C. Read Status​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "order_update_123",
  "subscriberId": "919672242292",
  "status": "read",
  "readAt": 1788939570
}

D. Failed Status​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "order_update_123",
  "subscriberId": "919672242292",
  "status": "failed",
  "failedAt": 1788939565,
  "errorCode": 131026,
  "failureReason": "Message Undeliverable",
  "failureDetails": "Recipient phone number not registered on WhatsApp"
}

Properties​

FieldTypeDescription
messageIdstringWhatsApp channel message ID (wamid.xxx)
messageRefstringCustom reference tag configured on the message node in Flow Builder or passed via API
subscriberIdstringRecipient customer phone number in international format without +
statusstringCurrent lifecycle status: sent, delivered, read, or failed
sentAt / deliveredAt / readAt / failedAtnumberUnix timestamp (epoch seconds) when the event occurred
errorCodenumberProvider failure code (present only on failure)
failureReasonstringHigh-level reason for failure (present only on failure)
failureDetailsstringDetailed error description from Meta (present only on failure)

2. Inbound Customer Messages​

Delivered when a customer sends a reply or initiates a message to your WhatsApp Business number.

A. Text Message​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "918000000000",
  "type": "text",
  "receivedAt": 1788939600,
  "text": "Hello, I want to know my order status."
}

B. Image Message​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "918000000000",
  "type": "image",
  "receivedAt": 1788939600,
  "mediaUrl": "https://s3.ap-south-1.amazonaws.com/media-storage/.../receipt.jpeg",
  "caption": "Payment receipt",
  "mimeType": "image/jpeg",
  "filename": "receipt.jpeg"
}

C. Document / PDF File​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "918000000000",
  "type": "file",
  "receivedAt": 1788939600,
  "mediaUrl": "https://s3.ap-south-1.amazonaws.com/media-storage/.../invoice.pdf",
  "caption": "Invoice copy",
  "mimeType": "application/pdf",
  "filename": "invoice.pdf"
}

D. Audio / Voice Note​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "918000000000",
  "type": "audio",
  "receivedAt": 1788939600,
  "mediaUrl": "https://s3.ap-south-1.amazonaws.com/media-storage/.../audio.ogg",
  "mimeType": "audio/ogg; codecs=opus",
  "filename": "voice_note.ogg"
}

E. Video​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "918000000000",
  "type": "video",
  "receivedAt": 1788939600,
  "mediaUrl": "https://s3.ap-south-1.amazonaws.com/media-storage/.../video.mp4",
  "caption": "Product issue video",
  "mimeType": "video/mp4",
  "filename": "issue.mp4"
}

F. Location Coordinates​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "918000000000",
  "type": "location",
  "receivedAt": 1788939600,
  "latitude": 12.971598,
  "longitude": 77.594566
}

G. NFM Reply​

Delivered when a customer submits a response through a WhatsApp Flow.

{
  "messageId": "wamid.HBgL12345",
  "subscriberId": "919999999999",
  "wabaNumber": "918000000000",
  "type": "nfm_reply",
  "receivedAt": 1788939600,
  "contextMessageId": "wamid.ORIGINAL123",
  "flowResponse": {
    "flowToken": "flow_token_abc",
    "name": "flow",
    "body": "Sent",
    "responseJson": {
      "rating": "5",
      "comment": "excellent"
    }
  }
}

H. Button Click​

WhatsApp button responses can arrive from Meta in either of the following formats.

Interactive Button Reply​

{
  "type": "interactive",
  "interactive": {
    "type": "button_reply",
    "button_reply": {
      "id": "btn_1",
      "title": "Yes"
    }
  }
}

Template Quick-Reply Button​

{
  "type": "button",
  "button": {
    "payload": "btn_1",
    "text": "Yes"
  }
}

Both incoming formats are normalized to this webhook event:

{
  "messageId": "wamid.HBgL12345",
  "subscriberId": "919999999999",
  "wabaNumber": "16505551234",
  "type": "button_click",
  "receivedAt": 1727180000,
  "buttonId": "btn_1",
  "buttonText": "Yes"
}

Properties​

FieldTypeDescription
messageIdstringWhatsApp channel message ID (wamid.xxx)
subscriberIdstringCustomer phone number without +
wabaNumberstringBusiness WhatsApp number that received the message
typestringMessage type: text, image, file, audio, video, location, nfm_reply, or button_click
receivedAtnumberUnix timestamp (epoch seconds) when received
textstringMessage body text (for text type)
mediaUrlstringDirect download URL for the media attachment
captionstringMedia caption text (if attached)
mimeTypestringMIME format of the media (e.g., image/jpeg, application/pdf)
filenamestringFilename of the media attachment
latitude / longitudenumberGPS coordinates (for location type)
contextMessageIdstringID of the message associated with an NFM reply
flowResponseobjectWhatsApp Flow response data for an nfm_reply, including the submitted responseJson
buttonIdstringButton payload/ID for a normalized button_click event
buttonTextstringButton label for a normalized button_click event

Response​

  • HTTP Status Code: 200 OK (successful), 4xx/5xx (error)